Set up npm release workflow for @onkernel/cua-cli - #28
Conversation
rgarcia
left a comment
There was a problem hiding this comment.
Reviewed against release-cua-ai.yml / release-cua-agent.yml, ci.yml's cli-unit job, and the existing docs/npm-releases.md conventions. Verified locally from a clean checkout of this branch: npm ci, builds for cua-ai/cua-agent/cua-cli, cua-cli unit tests (29 passed, 4 skipped without the native binding), npm pack, actionlint on the new workflow (clean), and npm view for every pinned runtime dep (@onkernel/cua-ai@0.3.0, @onkernel/cua-agent@0.3.3, @onkernel/sdk@0.49.0, @earendil-works/*@0.79.1 — all published).
Workflow fidelity checks out: correct tag prefix and version-check path, tag-on-main guard, id-token: write, npm >= 11.5.1 for trusted publishing, zig/ptywright cache + install steps verbatim from ci.yml, dep-publish verification fails correctly on missing versions (E404 → xargs exit 123 → step failure), the smoke test invokes the installed bin rather than importing the module (required, since dist/cli.js runs main() on import), and publish can only fire on cua-cli/v* tags whose commit is on main. package.json metadata matches the packages/ai / packages/agent conventions; ptywright is dev-only and nothing under packages/cli/src imports it; the tarball contains dist + README.md only, with both smoke-test grep targets present in the help text.
Findings
1. (major) The manual first-publish runbook publishes a broken bin as of this branch. Reproduced: pack the tarball, install into a fresh project, ./node_modules/.bin/cua --help → ERR_MODULE_NOT_FOUND for dist/cli-harness (tsc under moduleResolution: Bundler emits extensionless relative specifiers that Node ESM rejects). The release workflow's smoke test guards tag-driven releases, but the "Releasing @onkernel/cua-cli 0.1.0" section has no equivalent check — a maintainer following it verbatim today ships a broken 0.1.0, and published npm versions are immutable. Fix within this PR's scope: add a pre-publish smoke step to the doc between steps 3 and 4 (npm pack --workspace @onkernel/cua-cli --pack-destination "$(mktemp -d)", npm install the tarball into a fresh temp project, run ./node_modules/.bin/cua --help), and state that the publish must not proceed until it passes. The underlying specifier fix (bundler build like tsdown, or explicit .js extensions in source) is rightly out of scope here, but the runbook must not green-light a publish before that lands. Relatedly, the PR body's "the smoke test is the safety net before any tarball goes to npm" only holds for the tag-driven path — the manual path this PR documents has no safety net.
2. (minor) package-lock.json wasn't regenerated for the packages/cli metadata change. The lockfile's packages/cli entry lacks the new license and engines fields (the packages/ai and packages/agent entries carry "license": "MIT"). npm ci still passes, but the next npm install anyone runs will dirty the lockfile with this PR's leftovers. Apply just the packages/cli entry update — note a full npm install --package-lock-only also picks up ~411 lines of pre-existing drift already present on main, which should stay out of this PR.
3. (nit) The doc's dependency note reads as exhaustive but isn't. It lists @onkernel/cua-ai, @onkernel/cua-agent, @onkernel/sdk as the runtime deps that must be on npm, but @earendil-works/pi-coding-agent and @earendil-works/pi-tui are also exact-pinned runtime deps (both published at 0.79.1). Either drop the parenthetical or make the list complete.
Scope is otherwise exactly right — three files, no source changes, and the judgment calls (30-minute timeout for the serialized native build, dual dep verification, verbatim ci.yml toolchain steps, specific usage-line greps) are all sound.
- docs: add pre-publish smoke test step (npm pack + install + cua --help) to the first-publish runbook, so a maintainer following it verbatim does not ship a broken 0.1.0 to npm. - docs: list @earendil-works/pi-coding-agent and @earendil-works/pi-tui alongside the @onkernel runtime deps that must already be published. - package-lock.json: bring the packages/cli entry in line with the packages/ai and packages/agent entries by adding license MIT and engines node >=22.19.0 to match the package.json metadata.
|
Created a monitoring plan for this PR. What this PR does: Wires up Intended effect: No production telemetry signal exists for this CI/tooling change. The only observable output is a successful Risks:
Status updates will be posted automatically on this PR as monitoring progresses. |
Summary
@onkernel/cua-cli,mirroring the existing
release-cua-ai.yml/release-cua-agent.ymlworkflows triggered by package-specific tags.
packages/cli/package.jsonpublish-ready: addedlicense: MIT,repository(withdirectory: packages/cli),bugs,homepage,publishConfig.access: public, andengines.node: >=22.19.0to match theworkspace root.
.github/workflows/release-cua-cli.ymlon tagcua-cli/v*thatverifies the tag commit is on
main, installs Node 24 + npm >= 11.5.1 forOIDC trusted publishing, runs
npm ci, asserts the tag version matchespackages/cli/package.json, sets up Zig 0.15.2 + caches for the ptywrightnative build (replicating the
cli-unitjob inci.yml), builds theworkspace, verifies the pinned
@onkernel/cua-aiand@onkernel/cua-agentruntime dependency versions are published on npm, runs the cua-cli unit
tests with
PTYWRIGHT_REQUIRED=1, packs the tarball, installs it into afresh temp project and runs
./node_modules/.bin/cua --help(assertingexit 0 and that the usage banner is present), then
npm publish --access publicvia OIDC.docs/npm-releases.md: added the cua-cli row to the tag list,trusted-publisher table, and
npm trustexample, and a new"Releasing
@onkernel/cua-cli0.1.0" section that spells out the manualfirst-publish steps (npm requires the package to exist before a trusted
publisher can be configured) plus the post-publish trusted-publisher
configuration and the subsequent tag-driven release flow.
Why
@onkernel/cua-cli(now atpackages/cli) is the third workspace package inthe release series and previously had no release pipeline. This wires it up
following the same tag + OIDC pattern already used by
@onkernel/cua-aiand@onkernel/cua-agent.Test plan
npm ciclean from a fresh checkoutnpm run build --workspace @onkernel/cua-aisucceedsnpm run build --workspace @onkernel/cua-agentsucceedsnpm run build --workspace @onkernel/cua-clisucceeds (tsc -b)npm test --workspace @onkernel/cua-clipasses (29 passed, 4 skippeddue to missing ptywright native binding in this sandbox)
npm pack --workspace @onkernel/cua-cliproducesonkernel-cua-cli-0.1.0.tgzmanual 0.1.0 bootstrap publish and trusted-publisher configuration
npm publish --workspace @onkernel/cua-clifrom amaintainer machine — out of scope for this PR (see
docs/npm-releases.md)Open concern
The packed
cuabin currently fails when invoked as Node ESM because the CLIsource uses bare relative imports (e.g.
from "./cli-harness") andtsc -bdoes not rewrite them to./cli-harness.js. Vitest masks thisduring tests, and the workflow's smoke step (
./node_modules/.bin/cua --help) will surface it the moment the workflow runs end-to-end. Fixing it(switch the cli build to tsdown like cua-ai/cua-agent, or add
.jsextensions to the source imports) is intentionally out of scope for this PR
since the rule was to set up release machinery without modifying CLI source
beyond
package.json; the smoke test is the safety net before any tarballgoes to npm.
Note
Low Risk
Changes are CI, package metadata, and documentation only; no runtime application logic. Publish gates (tests, dependency checks, bin smoke test) reduce release risk.
Overview
Adds tag-driven npm releases for
@onkernel/cua-clivia a new workflow oncua-cli/v*, aligned with the existingcua-ai/cua-agentrelease pattern.release-cua-cli.ymlchecks the tag is onmainand matchespackages/cli/package.json, uses OIDC trusted publishing (Node 24, npm ≥ 11.5.1), builds workspace packages plus the ptywright native binding (Zig 0.15.2 + cache), confirms pinned@onkernel/cua-ai/@onkernel/cua-agentversions exist on npm, runs CLI tests withPTYWRIGHT_REQUIRED=1, pack + install smoke test (cua --help), then publishes publicly.packages/cli/package.jsonis made publish-ready (MIT license, repo/bugs/homepage,publishConfig.access: public,engines.node).docs/npm-releases.mddocuments thecua-clitag, trusted publisher row/npm trustcommand, and a manual first publish path before trusted publishing can be configured, then tag-based releases from0.1.1+.Reviewed by Cursor Bugbot for commit 62a47ed. Bugbot is set up for automated code reviews on this repo. Configure here.